Release 10.1A: OpenEdge Development:
Progress 4GL Reference

COMBO-BOX phrase

Describes a combo-box widget. A combo-box represents a field or variable, and consists of a field value and an associated drop-down list of possible values.

Note: Does not apply to SpeedScript programming.

Syntax

COMBO-BOX [ LIST-ITEMS item-list | LIST-ITEM-PAIRS item-pair-list ] [ INNER-LINES lines ] [ size-phrase ] [ SORT ] [ TOOLTIP tooltip ] [ SIMPLE | DROP-DOWN | DROP-DOWN-LIST ] [ MAX-CHARS characters ] [ AUTO-COMPLETION [ UNIQUE-MATCH ] ]

LIST-ITEMS item-list

Specifies the items to appear in the drop-down list. item-list represents a comma-separated list of valid values for the field or variable.

LIST-ITEM-PAIRS item-pair-list

Specifies a list of label-value pairs. Each pair represents the label and value of a field or variable. When the drop-down list appears, it displays each pair’s label. Then, if the user selects a label, Progress assigns the corresponding value to the field or variable. The syntax for item-pair-list is as follows:

label , value [ , label , value ] ...

label

A character string representing the label of the field or variable.

value

A value that Progress assigns to the field or variable if the user selects the corresponding label.

INNER-LINES lines

Specifies the number of lines visible in the drop-down list for a DROP-DOWN or DROP-DOWN-LIST combo-box widget. The value for lines must be 3 or greater. If the number of lines you specify is less than the number of items in the drop-down list, the list is scrollable.

The INNER-LINES option in a SIMPLE combo-box definition is ignored.

size-phrase

Specifies the outside dimensions (width and height) of the combo-box widget and its drop-down list using the SIZE phrase. You must specify a SIZE phrase in the definition of a SIMPLE or DROP-DOWN combo-box widget. The syntax for the SIZE phrase is as follows:

{ SIZE | SIZE-CHARS | SIZE-PIXELS } width BY height

For more information, see the SIZE phrase reference entry.

Note: The height value is ignored for DROP-DOWN and DROP-DOWN-LIST combo-box widgets. The height is always set to the height of a fill-in for the current font.

SORT

Specifies that list items be sorted prior to display.

TOOLTIP tooltip

Allows you to define a help text message for a text field or text variable. Progress automatically displays this text when the user pauses the mouse button over a text field or text variable for which a tooltip is defined.

You can add or change the TOOLTIP option at any time. If TOOLTIP is set to “” or the Unknown value (?), then the tooltip is removed. No tooltip is the default. The TOOLTIP option is supported in Windows only.

SIMPLE

Specifies a combo-box widget with a read/write edit control and a list that is always visible. This option is supported in graphical interfaces only, and only in Windows. If you specify a SIMPLE combo-box widget in a character interface, Progress treats it as a DROP-DOWN-LIST combo-box widget.

DROP-DOWN

Specifies a combo-box widget with a read/write edit control and a drop-down list that appears when you click the drop-down button. This option is supported in graphical interfaces only, and only in Windows. If you specify a DROP-DOWN combo-box widget in a character interface, Progress treats it as a DROP-DOWN-LIST combo-box widget.

DROP-DOWN-LIST

Specifies a combo-box widget with a read-only edit control and a drop-down list that appears when you click the drop-down button. This is the default.

MAX-CHARS characters

The maximum number of characters the edit control can hold. The characters parameter must be a positive integer constant. If characters is zero or the Unknown value (?), MAX-CHARS is set to 255 characters by default.

Use MAX-CHARS with only SIMPLE and DROP-DOWN combo-boxes. It is ignored for DROP-DOWN-LIST combo-boxes. This option is supported in graphical interfaces only, and only in Windows.

AUTO-COMPLETION

Specifies that the edit control automatically complete keyboard input to the combo-box, based on a potential match, by searching through the items in the drop-down list. This option is supported in graphical interfaces only, and only in Windows.

UNIQUE-MATCH

Specifies that the edit control complete keyboard input to the combo-box based on a unique match. This option is supported in graphical interfaces only, and only in Windows.

Examples

The first example, r-combo.p, views a date field as a combo-box. When you run this procedure, you can choose a date value from the drop-down list. When you choose a new value, the VALUE-CHANGED trigger updates the value of out-string to an event associated with the new date value.

The example initializes the drop-down list by building a comma-separated list of values and then assigning the string to the LIST-ITEMS attribute of the combo-box.

r-combo.p

DEFINE VARIABLE hist-date AS DATE FORMAT "99/99/9999" VIEW-AS COMBO-BOX LIST-ITEMS 07/04/1776, 07/11/1969, 09/10/1993. DEFINE VARIABLE hist-event AS CHARACTER INITIAL "Declaration of Independence,Man walks on moon,Progress Version 7 ships". DEFINE VARIABLE out-string AS CHARACTER FORMAT "x(36)". DEFINE FRAME main-frame hist-date out-string WITH NO-LABELS TITLE "Historic Events". ON VALUE-CHANGED OF hist-date DO: out-string = ENTRY(SELF:LOOKUP(SELF:SCREEN-VALUE), hist-event). DISPLAY out-string WITH FRAME main-frame. END. ENABLE hist-date WITH FRAME main-frame. APPLY "VALUE-CHANGED" TO hist-date IN FRAME main-frame. WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW.

The following example, r-combo.p, builds a combo-box based on field values from a database. It defines triggers that allow you to change the value of the combo-box without displaying the drop-down list. They allow you to scroll through the values using the CURSOR-DOWN and CURSOR-UP keys or to jump to a specific value by typing its first letter.

r-combo2.p

DEFINE VARIABLE i AS INTEGER. DEFINE VARIABLE rep AS CHARACTER LABEL "Rep" VIEW-AS COMBO-BOX. DEFINE VARIABLE temp-string AS CHARACTER. FORM rep WITH FRAME main-frame SIDE-LABELS. ON ANY-PRINTABLE OF rep DO: /* Find the first entry in the drop-down list that begins with the character typed. Set the SCREEN-VALUE of the combo box to that value. */ seek-item: DO i = 1 TO SELF:NUM-ITEMS: IF SELF:ENTRY(i) BEGINS LAST-EVENT:FUNCTION THEN DO: SELF:SCREEN-VALUE = SELF:ENTRY(i). LEAVE seek-item. END. END. IF i > SELF:NUM-ITEMS THEN BELL. END. ON CURSOR-DOWN OF rep DO: /* Change the SCREEN-VALUE of the combo box to the next value from the drop-down list. */ i = SELF:LOOKUP(SELF:SCREEN-VALUE). IF i < SELF:NUM-ITEMS THEN SELF:SCREEN-VALUE = SELF:ENTRY(i + 1). END. ON CURSOR-UP OF rep DO: /* Change the SCREEN-VALUE of the combo box to the prev value from the drop-down list. */ i = SELF:LOOKUP(SELF:SCREEN-VALUE). IF i > 1 THEN SELF:SCREEN-VALUE = SELF:ENTRY(i - 1). END.temp-string = "". FOR EACH Salesrep NO-LOCK: IF temp-string = "" THEN temp-string = Salesrep.sales-rep. ELSE temp-string = temp-string + "," + Salesrep.sales-rep. END. ASSIGN rep:LIST-ITEMS IN FRAME main-frame = temp-string. ENABLE rep WITH FRAME main-frame.

Notes

When the drop-down list appears, if it contains the value associated with the field or variable, that value is initially highlighted. Otherwise, no value in the drop-down list is initially highlighted.
The LIST-ITEMS option of the COMBO-BOX phrase requires a list of items (possibly quoted, depending on the combo-box’s data type), such as ("a", "b", "c"), whereas the LIST-ITEMS attribute of a combo-box requires a quoted list of items, such as ("a, b, c"). Similarly, the LIST-ITEM-PAIRS option of the COMBO-BOX phrase requires a list of items (possibly quoted, depending on the combo-box’s data type), such as ("a", 1, "b", 2, "c", 3), whereas the LIST-ITEM-PAIRS attribute of a combo-box requires a quoted list of items, such as ("a, 1, b, 2, c, 3").
If you do not specify the LIST-ITEMS or LIST-ITEM-PAIRS option, the screen value of the variable or field becomes the null string (" "). To display or set values in the combo-box, you must first set the LIST-ITEMS or LIST-ITEM-PAIRS attribute to assign a drop-down list that specifies the available values.
If you specify the SORT option for a COMBO-BOX, then any items you add with the ADD-FIRST, ADD-LAST, or INSERT methods are added in sorted order rather than the order you specify.
Windows allows the user to transfer focus to the drop-down list by pressing ALT and one of the letters in the label. This is called a mnemonic.
When you use the SIMPLE and DROP-DOWN options to define a character-field or character-variable combo-box widget, the FORMAT string for the field or variable is ignored.
Items in a combo-box are case insensitive.

See also

Format phrase, SIZE phrase, VIEW-AS phrase